Skip to content

Native: compress JSON responses like PHP's CompressResponse (Dev egress 385 → 106 KB/workflow) - #1261

Merged
rmcdaniel merged 3 commits into
mainfrom
general/egress-compression
Nov 20, 2026
Merged

rmcdaniel merged 3 commits into
mainfrom
general/egress-compression

Conversation

@rmcdaniel

@rmcdaniel rmcdaniel commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

Why

The Cloud Dev benchmark on native 3.15.0 was capped at 1.5 wf/s by the cell's 4 Mbit/s egress shaper, not by CPU. One cause is that native sends every answer uncompressed and advertises response_compression: []. PHP Server, by contrast, gzip- or deflate-encodes JSON answers of 1024 bytes or more (CompressResponse, DW_COMPRESSION_ENABLED, default true).

In a Dev cell the origin answers are the cell's egress: the Cloudflare tunnel carries them as the origin produced them, and cloudflared has no compression option. The Cloudflare edge always asks the origin for accept-encoding: br, gzip and decompresses for clients that didn't ask (Cloudflare docs). So this change reduces tunnel egress for every existing SDK, with no client or Cloud change.

What

  • New middleware response_compression, the outermost layer on the router. It follows PHP's CompressResponse:
    • It prefers gzip over deflate at equal q, treats * as both, and treats q=0 as refused.
    • deflate is the zlib format (RFC 1950) that HTTP's deflate coding names, not raw DEFLATE.
    • It encodes JSON content types only, with a 1024-byte minimum.
    • It leaves an existing Content-Encoding alone and adds Vary: Accept-Encoding.
    • It encodes only bodies that are already in memory (exact size hint); streamed answers pass through.
    • Bodies over 256 KB are encoded on a blocking thread (spawn_blocking). At roughly 30 MB/s for level 6, an 8 MB body would otherwise hold one of the runtime's async workers for about 300 ms.
  • DW_COMPRESSION_ENABLED (and the legacy WORKFLOW_SERVER_COMPRESSION_ENABLED) is now Honored; it was Ignored before.
  • Cluster info advertises ["gzip","deflate"] when compression is enabled, as PHP does. The native deviation is removed from tests/Fixtures/ServerParity/cluster-capabilities.json.
  • History-page gzip reuses the same RFC 1952 encoder. Its behaviour is unchanged.

Measured (lab)

Setup

  • Native build of main with this change, in a 1 vCPU / 1 GiB slice that mimics a Dev cell: MySQL 8.0.46, the same limits as docker-compose.vultr-dev-runtime-native.yml.
  • DW Standard Workflow v1, PHP SDK 3.22.0 (unchanged), 1 wf/s, 4 workers, 1 s task polls, 1 s result polling.
  • A byte meter stands in for the tunnel. It asks the origin for br, gzip like the Cloudflare edge, and logs the origin bytes for each request ($upstream_bytes_received).
  • Window: 120 s. Every workflow was verified: result, completed status and typed history.
origin response bytes / workflow
main (same as published 3.15.0: 386 KB) 384.8 KB
main + this PR 106.0 KB (−72%)

CPU (lab slice, 1 vCPU, including MySQL):

The remaining bytes are mostly the ~17 KB server_capabilities object repeated in every worker answer (5.6 KB each after gzip). The companion PR (opt-in capabilities digest) removes those copies. With both PRs and the matching SDK change, the same run measured 18.4 KB/workflow.

Tests

  • Unit (response_compression):
    • PHP's encoding preference table, the setting and its legacy name.
    • A gzip round trip with CRC and length checks, and a zlib deflate round trip with header checks.
    • A body over 256 KB encoded on the blocking path, for both encodings.
    • Pass-through for small, non-JSON, already-encoded and streamed answers.
    • An ignored encode_cost benchmark.
  • Updated: cluster-info unit and execution tests, the parity fixture, and tests/Unit/ServerParityClusterCapabilitiesContractTest.mjs. Native advertising no compression is now rejected.
  • Local runs:
    • cargo test --lib -- response_compression cluster_info config_audit history_pages: all passed (see the latest comment for counts).
    • cargo test --test execution -- activity_results: 5 passed.
    • node --test tests/Unit/ServerParityClusterCapabilitiesContractTest.mjs: 24 passed.

Cloud. Nothing to change: DW_COMPRESSION_ENABLED defaults to true and is already a known name for the strict env audit. Dev cells pick this up when they move to a Server release that contains it.

🤖 Generated with Claude Code

Native sent every answer uncompressed and advertised response_compression: [].
PHP Server gzip- or deflate-encodes JSON answers of 1024 bytes or more when
Accept-Encoding allows it (DW_COMPRESSION_ENABLED, default true).

On a Dev cell behind a Cloudflare tunnel the origin answers are the cell's
egress, which is shaped to 4 Mbit/s. The Cloudflare edge always asks the
origin for "br, gzip" and decodes for clients that did not ask, so this
reduces tunnel egress without any SDK change. Lab measurement (DW Standard
Workflow v1, 1 wf/s, 4 workers): 384.8 KB -> 106.0 KB of origin response
bytes per workflow.

- New response_compression middleware, outermost on the router: PHP's
  encoding preference (gzip over deflate at equal q, *, q=0), JSON content
  types only, 1024-byte minimum, existing Content-Encoding left alone,
  Vary: Accept-Encoding. Only in-memory (exact-sized) bodies are encoded;
  streamed answers pass through.
- DW_COMPRESSION_ENABLED (and its legacy name) is honored instead of ignored.
- cluster info advertises ["gzip", "deflate"] when enabled, as PHP does; the
  native deviation is removed from the parity fixture.
- History-page gzip reuses the same RFC 1952 encoder.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@rmcdaniel

Copy link
Copy Markdown
Member Author

Companion changes: server#1262 (opt-in capabilities digest) and sdk-php#446 (SDK gzip, digest, history-free result). The robustness issue observed under saturation is sdk-php#445.

rmcdaniel and others added 2 commits November 20, 2026 01:42
Review fixes:
- Bodies above 256 KB are encoded on a blocking thread (spawn_blocking).
  At roughly 30 MB/s for level 6, an 8 MB body would otherwise hold an async
  worker for about 300 ms on a 2-thread runtime.
- HTTP's deflate coding is the zlib format (RFC 1950), not raw DEFLATE;
  deflate answers are now zlib-wrapped.
- Tests: a large answer encodes on the blocking path and round-trips for
  gzip and deflate, the zlib header is checked, and an ignored benchmark
  reports encode cost by size.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
encode_cost (release, lab): 14 KB in 0.6 ms, 217 KB in 10 ms, 7 MB in
196 ms (22-36 MB/s).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@rmcdaniel

Copy link
Copy Markdown
Member Author

Review fixes pushed: bodies over 256 KB now compress on a blocking thread, deflate is zlib-wrapped, and there is an ignored encode_cost benchmark. Measured in a release build: 14 KB in 0.6 ms, 217 KB in 10 ms, 7 MB in 196 ms (22-36 MB/s). Local runs: cargo test --lib -- response_compression cluster_info config_audit history_pages: 30 passed (1 ignored). cargo test --test execution -- activity_results: 5 passed. The PR body's CPU evidence is corrected.

@sonarqubecloud

Copy link
Copy Markdown

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant